home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d20 / vmgr112.arc / VOTEMGR.DOC < prev    next >
Text File  |  1991-09-17  |  23KB  |  732 lines
  1.     
  2.   ------------------------------------------------------------------
  3.  
  4.                              votemgr 1.12
  5.  
  6.                 - a vote manager for fidonet systems -
  7.  
  8.                             Aug  29, 1991
  9.  
  10.  
  11.                              USER MANUAL
  12.  
  13.  
  14.                  Copyright (c) 1991-19xx Carlos Terre
  15.                          All Rights Reserved.
  16.  
  17.                        Written by Carlos Terre
  18.                 Documentation written by Carlos Terre
  19.  
  20.   ------------------------------------------------------------------
  21.  
  22.  ---------------
  23.  -2  WHAT'S NEW
  24.  ---------------
  25.  
  26.     *   Some bug fixes, and some new features... Just smoothing!
  27.  
  28.     *   WARNING!!! Command line parsing has been changed!!!
  29.  
  30.         Check your Batch files when upgrading!
  31.  
  32.  
  33.  
  34.  ---------------------
  35.  -1  ACKNOWLEDGEMENTS
  36.  ---------------------
  37.  
  38.         I owe Orlando Castillo (2:346/4) the idea of this program, his
  39.     help when debugging votemgr, and his enthusiasm that kept my
  40.     attention on the project. Thanks orlando! We did it ;-)
  41.  
  42.         I want to thank all members of net 2:348 who helped
  43.     me test and debug votemgr.
  44.  
  45.         VOTEMGR was first used in March 1991 when electing RC in
  46.     region 2:34
  47.  
  48.  
  49.  
  50.  -----------------------
  51.  0   THE LEGAL BUSINESS
  52.  -----------------------
  53.  
  54.         VOTEMGR is guaranteed only to take up space on your hard disk.
  55.     Use it at your own risk. No warranty is stated or implied. The
  56.     author shall not be responsible for any damages resulting  from
  57.     it's  use, directly or indirectly.
  58.  
  59.         VOTEMGR unregistered version is distributed as a Freely
  60.     Available Copyrighted Program, provided it is used in a
  61.     NONCOMMERCIAL environment: You can use it as long as you do not
  62.     use it within a commercial environment. It doesn't matter if you
  63.     are making money by using it or not, if you are using it within
  64.     commercial walls, you may not use the noncommercial version. No
  65.     fee may be charged for distribution and the distribution archive
  66.     is not to be tampered with or altered in ANY way.
  67.  
  68.         VOTEMGR cannot be distributed in a modified form of any sort.
  69.  
  70.         VOTEMGR can no longer be repackaged for distribution.
  71.     Distribution file must not be changed in any way. No additional
  72.     files may be included and original files may not be modified.
  73.  
  74.         While VOTEMGR unregistered version is freely available for
  75.     use in non-corporate environments, you can register your copy by
  76.     sending a donation to the author. I ask for $10.00, but if you
  77.     just can't aford it... we surely can arrange it! Don't waste your
  78.     time wondering how to send me your money: just enclose a bill in an
  79.     envelope (no matter what currency) and post it. I strongly encourage
  80.     everybody to register. You will only have to register once, since
  81.     your key will work with the next major release (2.00).
  82.  
  83.         Registered users will have support.
  84.  
  85.         Send donations to:
  86.  
  87.         Carlos Terre
  88.         p/Compostela 25, 5
  89.         36201 VIGO (Spain)
  90.  
  91.         You can contact me at the following network addresses:
  92.  
  93.         Carlos Terre    2:343/108@fidonet
  94.                         2:348/1.25@fidonet
  95.  
  96.  
  97.  
  98.  -------------------------------------------
  99.  1   THE DISTRIBUTION ARCHIVE (VMGR112.ARJ)
  100.  -------------------------------------------
  101.  
  102.         This archive should have included the following files:
  103.  
  104.           VOTEMGR.DOC    -  The Documentation, you read it as we speak.
  105.           VOTEMGR.EXE    -  The Executable Program.
  106.           VOTEMGR.CTL    -  A Control File example.
  107.           VMGRUSER.DOC   -  A voters guide for using votemgr.
  108.           *.TXT          -  Sample TXT files.
  109.  
  110.  
  111.  
  112.  -----------------
  113.  2   WHAT IT DOES
  114.  -----------------
  115.  
  116.         VOTEMGR is meant to take charge of votings carried on at your
  117.     system. It is designed in such a way that "voters" can send
  118.     messages to it, the same way they send messages to AREAMGR,
  119.     AREAFIX, or FILEEFIX: voters actually "talk" to votemgr.
  120.  
  121.         In return, votemgr will send messages to voters (if you decide
  122.     so) to keep them informed of possible errors or to, simply,
  123.     acknowledge correct ballot processing.
  124.  
  125.         You can edit your own messages editing ASCII files that will
  126.     be defined in the control file.
  127.  
  128.         Here is what "vote manager" will be up to:
  129.  
  130.     SPECIFICATIONS:
  131.  
  132.         o Up to 25 different votings at a time.
  133.         o Value added error control and result computation.
  134.         o Feedback messages to voters.
  135.         o Full control of receipt messages text.
  136.         o Full control of Dates and electoral periods.
  137.         o Logging of activities.
  138.         o Processed messages moving them to a backup directory
  139.                 (*.MSG format).
  140.         o Backup copies of processed ballots kept apart.
  141.         o Results posted into standard packets for tossing in the area
  142.                 of your choice.
  143.         o Errorlevels reported to DOS.
  144.  
  145.     SPECIFICATIONS FOR EACH VOTING:
  146.  
  147.         o Up to 100 different choices.
  148.         o Up to 100 validation keys for systems ("ALL" macro is OK)
  149.         o Up to 100 rejection keys for systems ("ALL" macro is OK)
  150.         o Full description of the election and results with TXTfiles.
  151.         o Public/Secret result reports.
  152.         o NULL votes controled.
  153.         o Full control of point systems' validation.
  154.  
  155.  
  156.  
  157.  ---------------------------------
  158.  3   DISK AND MEMORY REQUIREMENTS
  159.  ---------------------------------
  160.  
  161.     Anything will, most likely, do ;-)
  162.  
  163.         Should you have trouble, drop me a message!
  164.  
  165.  
  166.  
  167.  -----------------------------------
  168.  4   THE CONTROL FILE : VOTEMGR.CTL
  169.  -----------------------------------
  170.  
  171.         In order to know your system configuration, and to define what
  172.     your votings will be about, you must edit a plain vanilla ASCII
  173.     file called VOTEMGR.CTL (actually, VOTEMGR.EXE can be renamed to
  174.     whatever you like best, and then the .CTL file must be renamed
  175.     too).
  176.  
  177.         The .CTL file must be in the same directory as the .EXE file.
  178.  
  179.         VOTEMGR.CTL structure can be devided in three groups:
  180.  
  181.             . general options
  182.             . receipt text files
  183.             . election definition block structure
  184.  
  185.         Each of these different groups defines different types of
  186.     parameters votemgr needs to work. Parameters are entered following
  187.     a KEYWORD, and order is not significant "most of the times".
  188.  
  189.         Strings containing spaces must be linked with underscores '_'
  190.  
  191.         Items enclosed in square brackets ([]) are optional
  192.  
  193.         Directories no longer need be terminated with a backslash '\'
  194.  
  195.  
  196.  
  197.     4.1  General Options
  198.     --------------------
  199.  
  200.  
  201.     4.1.1   USERCODE
  202.  
  203.             USERCODE <1stname_lastname> [<regkey>]
  204.  
  205.             If your copy is not registered, you must simply enter your
  206.         name. This parameter is mandatory.
  207.  
  208.  
  209.     4.1.2   ADDRESS
  210.  
  211.             ADDRESS  z:net/node[.point]
  212.  
  213.             Your fidonet address. This parameter is mandatory.
  214.  
  215.  
  216.     4.1.4   NETMAIL
  217.  
  218.             NETMAIL  <path>
  219.  
  220.             Your NET Mail directory (where *.MSG files area stored).
  221.         This parameter is mandatory.
  222.  
  223.  
  224.     4.1.5   WORKPATH
  225.  
  226.             WORKPATH <path>
  227.  
  228.             Directory where votemgr will store results and temporary
  229.         files. This directory defaults to the directory where
  230.         votemgr.exe is stored. This parameter is optional.
  231.  
  232.  
  233.     4.1.6   INBOUND
  234.  
  235.             INBOUND <path>
  236.  
  237.             Your inbound directory. This is where packets with results
  238.         will be created. This is the directory your echomail processor
  239.         should look for packets in. This parameter is optional.
  240.  
  241.  
  242.     4.1.7   ORIGINLINE
  243.  
  244.             ORIGINLINE
  245.             <origin line>
  246.  
  247.             Your origin line for votemgr echo messages containing
  248.         results. Note that this keyword instructs votemgr to read the
  249.         next line in the control file as the origin line, so no
  250.         comments should be placed in the line after the keyword
  251.         "originline". This parameter is optional.
  252.  
  253.  
  254.     4.1.8   MOVEPATH
  255.  
  256.             MOVEPATH <path>
  257.  
  258.             Default 'moving' directory. All messages addressed to
  259.         votemgr will be moved by default to this directory unless
  260.         other directory is later specified. This parameter is
  261.         optional.
  262.  
  263.  
  264.     4.1.9   LOGFILE
  265.  
  266.             LOGFILE <file_spec>
  267.  
  268.             Log file for logging votemgr activities.
  269.  
  270.  
  271.     4.1.10  STATUS
  272.  
  273.             STATUS {pkhcsd}
  274.  
  275.             Return receipt message status. Here you can set the status of
  276.         the messages that votemgr will send to voters. All you have to
  277.         do is build up a string with the letters of the status you
  278.         want activated:
  279.  
  280.             p -> private
  281.             k -> kill
  282.             h -> hold
  283.             c -> crash
  284.             s -> sent
  285.             d -> direct
  286.  
  287.             Note that if you don't want votemgr to send feedback
  288.         messages to voters you must flag them as SENT.
  289.  
  290.  
  291.     4.1.11  KILLPROCESSED
  292.  
  293.             KILLPROCESSED
  294.  
  295.             If you want votemgr to erase processed messages, place
  296.         this keyword in your control file. The default procedure is to
  297.         flag them RECEIVED. Note that those messages subject to be
  298.         moved will -NOT- be erased. This is: KillProcessed is
  299.         overridden by "move" keywords.
  300.  
  301.  
  302.  
  303.     4.2  Receipt Text Files
  304.     -----------------------
  305.  
  306.         These files should be plain vanilla ASCII texts.
  307.  
  308.  
  309.     4.2.1   ACTIVETXT
  310.  
  311.             ACTIVETXT <file_spec>
  312.  
  313.             This text is the main header of the body of the message
  314.         addressed to voters when they request information about active
  315.         votings held at your system.
  316.  
  317.  
  318.     4.2.2   CHOICESTXT
  319.  
  320.             CHOICESTXT <file_spec>
  321.  
  322.             This text is the main header of the body of the message
  323.         addressed to voters when they request information about the
  324.         valid choices for one particular voting held at your system.
  325.  
  326.             Following this text, the list of valid choices for a
  327.         particular election will be displayed.
  328.  
  329.  
  330.     4.2.3   RECEIPTTXT
  331.  
  332.             RECEIPTTXT <file_spec>
  333.  
  334.             This text is the body of the message addressed to voters
  335.         when their ballot has been successfully processed by votemgr.
  336.  
  337.  
  338.     4.2.4   DUPLICATETXT
  339.  
  340.             DUPLICATETXT <file_spec>
  341.  
  342.             This text is the body of the message addressed to voters
  343.         when they try to vote twice and one ballot has already been
  344.         successfully processed by votemgr for one particular election.
  345.         Obviously, one person can only send one ballot to one
  346.         particular voting.
  347.  
  348.  
  349.     4.2.5   ERRVOTTXT
  350.  
  351.             ERRVOTTXT <file_spec>
  352.  
  353.             This text is the main header of the body of the message
  354.         addressed to voters when they make a mistake (or typo) when
  355.         they refer to a voting which is *not* defined at your system.
  356.  
  357.             This text should explain that an error has ocurred, and
  358.         that they should send another message correcting the error.
  359.  
  360.             Following this text, ACTIVETXT will be displayed; and
  361.         after it, the list of active votings held at your system.
  362.  
  363.  
  364.  
  365.     4.2.6   ERRCHOICETXT
  366.  
  367.             ERRCHOICETXT <file_spec>
  368.  
  369.             This text is the main header of the body of the message
  370.         addressed to voters when they make a mistake (or typo) in
  371.         their ballot. This text should explain that an error has
  372.         ocurred, and that they should send another ballot correcting
  373.         the error.
  374.  
  375.             Following this text, CHOICESTXT will be displayed; and
  376.         after it, the list of valid choices for the particular voting.
  377.  
  378.  
  379.     4.2.7   ERRVALTXT
  380.  
  381.             ERRVALTXT <file_spec>
  382.  
  383.             This text is the body of the message addressed to persons
  384.         who try to vote even though they are not validated.
  385.  
  386.  
  387.     4.2.8   TOOLATETXT
  388.  
  389.             TOOLATETXT <file_spec>
  390.  
  391.             This text is the body of the message addressed to voters
  392.         when their ballot is received too late, and therefore will
  393.         *not* be processed by votemgr.
  394.  
  395.             This text should contain a message telling the voter to
  396.         contact votemgr supervisor.
  397.  
  398.  
  399.     4.2.9   TOOSOONTXT
  400.  
  401.             TOOSOONTXT <file_spec>
  402.  
  403.             This text is the body of the message addressed to voters
  404.         when their ballot is received too soon, and therefore will
  405.         *not* be processed by votemgr.
  406.  
  407.             This text should contain a message telling the voter to
  408.         try again within the electoral period.
  409.  
  410.  
  411.  
  412.     4.3  Election Definition Block Structure
  413.     ----------------------------------------
  414.  
  415.             This block can be repeated as many as 25 times, defining 25
  416.         different votings at your system.
  417.  
  418.  
  419.     4.3.1   DEFINE
  420.  
  421.             DEFINE <electname>
  422.  
  423.             Definition block start mark. <electname> MUST be a valid
  424.         DOS file name (max 8 chars). votemgr will use this name to
  425.         create temporary files related with the voting defined, in the
  426.         work or default directory.
  427.  
  428.             DEFINE has its counterpart in ENDDEF, which is the block
  429.         end mark. Both must always be used!.
  430.  
  431.  
  432.     4.3.2   VALIDATE
  433.  
  434.             VALIDATE <address [{address}]>
  435.  
  436.             Validate statements allow you to specify who is allowed to
  437.         vote. You can write multiple addresses following one VALIDATE
  438.         statement, and you can use as many VALIDATE statements as you
  439.         need (provided no more than 100 addresses are specified in
  440.         total).
  441.  
  442.             <address> can be either a particular address or a set of
  443.         addresses gathered by means of the ALL macro. ALL macro is
  444.         supported. When entering an address, you may specify ALL in
  445.         any, or all, address portions (the 4 valid address portions
  446.         are:  Zone, Net, Node and Point).
  447.  
  448.             Note that wildcarding will *NOT* auto-flow in a greater to
  449.         lesser direction, IN CASE YOU DON'T SPECIFY A RULE FOR LESSER
  450.         DIRECTION. That means that if you specify ALL in the Net
  451.         position, Node and Point will not be wildcarded, and will
  452.         default to 0 provided you don't write ANYTHING in the node and
  453.         point position (i.e. 2:ALL becomes 2:ALL/0.0; but if you enter
  454.         2:ALL/ALL "ALL" nodes in zone 2 will be wildcarded.).
  455.  
  456.             The most general rule is, then, all:all/all.all which
  457.         validates whatever address you may think of.
  458.  
  459.             This is a very powerfull feature, and should be used
  460.         together with the REJECT statement, explained below.
  461.  
  462.  
  463.  
  464.     4.3.3   REJECT
  465.  
  466.             REJECT <address [{address}]>
  467.  
  468.             Reject statements allow you to specify who is *not*
  469.         allowed to vote. You can write multiple addresses following
  470.         one Reject statement, and you can use as many Reject
  471.         statements as you need (provided no more than 100 addresses
  472.         are specified in total).
  473.  
  474.             This statement follows the same rules as VALIDATE, and is
  475.         intended for use with VALIDATE in order to make exceptions to
  476.         global VALIDATE statements. i.e.:
  477.  
  478.                 VALIDATE 2:343/ALL.0
  479.                 REJECT   2:343/100 2:343/200 2:343/300
  480.  
  481.  
  482.     4.3.4   AREA
  483.  
  484.             AREA <area_tag>
  485.  
  486.             EchoMail Area TAG of the echomail conference for which
  487.         packets will be created in your inbound directory. This TAG
  488.         must be known to your echomail processor. If no TAG is
  489.         specified, pakects will not be created.
  490.  
  491.  
  492.     4.3.5   FROMDATE
  493.  
  494.             FROMDATE <mm/dd/yyyy>
  495.  
  496.             Date of start of ballot processing. Ballots received
  497.         previous to this date, will be ignored, and addressee will be
  498.         notified so he can vote again.
  499.  
  500.  
  501.     4.3.6   TODATE
  502.  
  503.             TODATE <mm/dd/yyyy>
  504.  
  505.             Last day of ballot processing. Ballots received after this
  506.         date will be ignored, and addressee will be notified so he can
  507.         know.
  508.  
  509.  
  510.     4.3.7   MOVEPATH
  511.  
  512.             MOVEPATH <path>
  513.  
  514.             Directory where ballots (and only ballots) of this
  515.         voting will be moved to.
  516.  
  517.  
  518.     4.3.8   PRIVATE
  519.  
  520.             PRIVATE
  521.  
  522.             Instructs votemgr to hide names and addresses when
  523.         reporting results, so the voting is considered private.
  524.  
  525.  
  526.     4.3.9   NULLOK
  527.  
  528.             NULLOK
  529.  
  530.             Instructs votemgr to accept NULL ballots (ballots with a
  531.         vote for an unknown choice). Any ballot for an unlisted choice
  532.         will be considered to be a "null" vote.
  533.             Otherwise, votemgr would generate an error message addressed
  534.         to the voter and ballot would not be computed.
  535.  
  536.  
  537.     4.3.9b  UNLISTEDOK
  538.  
  539.             UNLISTEDOK
  540.  
  541.             Instructs votemgr to accept UNLISTED choices in ballots
  542.         (ballots with a vote for an unknown choice). Activate this
  543.         option if you want to accept unlisted choices -but still valid-
  544.         in ballots. Notice that if users don't type two unlisted choices
  545.         in the same way, two different entries will be produced when
  546.         reporting.
  547.             Otherwise, votemgr would generate an error message addressed
  548.         to the voter and ballot would not be computed.
  549.  
  550.  
  551.     4.3.10  INFOTXT
  552.  
  553.             INFOTXT <file_spec>
  554.  
  555.             Description of the election to be displayed in the active
  556.         votings list. This text should describe what the voting is
  557.         about and who is validated to vote.
  558.  
  559.  
  560.     4.3.11  RESULTTXT
  561.  
  562.             RESULTTXT <file_spec>
  563.  
  564.             This text will be the header for results. This text
  565.         defaults to INFOTXT if is left undefined.
  566.  
  567.  
  568.     4.3.12  CHOICES & ENDCHOICES
  569.  
  570.             CHOICES
  571.             ...
  572.             ENDCHOICES
  573.  
  574.             CHOICES keyword starts the list of valid choices for the
  575.         voting. Only one choice can be defined per line. Choices MUST
  576.         not contain spaces ' ' but rather underscores '_'.
  577.  
  578.             Up to 100 different choices can be defined for one
  579.         particular voting.
  580.  
  581.             ENDCHOICES keyword finishes the list of valid choices.
  582.  
  583.             For example:
  584.  
  585.                 CHOICES
  586.                 yes
  587.                 no
  588.                 blank
  589.                 ENDCHOICES
  590.  
  591.             (we declare three valid choices for a voting: "yes", "no" and
  592.             "blank")
  593.  
  594.  
  595.     4.3.13  ENDDEF
  596.  
  597.             ENDDEF
  598.  
  599.             Voting Definition block END marker. NOTICE! YOU MUST
  600.         ALWAYS FINISH YOU VOTING DEFINITION BLOCK!!!
  601.  
  602.  
  603.  
  604.  ------------------------
  605.  5   COMMAND LINE SYNTAX
  606.  ------------------------
  607.  
  608.  
  609.         Usage:  VOTEMGR [ -scan ] [{[ -r <voting_name> ] ... }]
  610.  
  611.             Items enclosed in [] are entirely optional.
  612.             Items enclosed in {} are a "list" of optional items.
  613.             Items enclosed in <> are parameters.
  614.  
  615.         Switches:
  616.  
  617.                 *  -scan
  618.  
  619.                    Instructs votemgr to scan your netmail directory
  620.                    looking for messages addressed to votemgr. You should
  621.                    include an external event and execute this command on
  622.                    a daily basis -at the least-.
  623.  
  624.                 *  -r <voting_name>
  625.  
  626.                    Instructs votemgr to create a report of the specified
  627.                    voting. If the electoral period has not expired yet,
  628.                    no packets will be created.
  629.                    If electoral period has expired, then packets will be
  630.                    created "once". A void file with extension .FLG will
  631.                    be created in the work directory to flag that packets
  632.                    have already been created.
  633.  
  634.  
  635.  
  636.  -------------
  637.  6   EXAMPLES
  638.  -------------
  639.  
  640.         This example relates to the included sample .CTL file:
  641.  
  642.             votemgr -scan -r nec343
  643.  
  644.         votemgr will scan your netmail for new ballots and will update
  645.     result files. Eventually, votemgr will create report packets for
  646.     tossing.
  647.  
  648.         You could use a longer command line if you wanted to create
  649.     reports on more than one voting:
  650.  
  651.             votemgr -scan -r nec343 -r encrypt -r moderato
  652.  
  653.         As you can see, not much is to be said about executing votemgr
  654.     from the command line ;-)
  655.  
  656.  
  657.  
  658.  -----------------
  659.  7   OUTPUT FILES
  660.  -----------------
  661.  
  662.             votemgr creates files in the work directory to keep results
  663.         and account of ballots. These files have the name of the related
  664.         voting, and four different extensions: .VOT, .RES, .QUO, .FLG
  665.  
  666.  
  667.     7.1  .VOT
  668.     ---------
  669.  
  670.             .VOT keeps every processed and correct ballot for one
  671.         voting. It stores information about voters, and should be kept
  672.         protected, since this information should only be available to
  673.         votemgr coordinator.
  674.  
  675.  
  676.     7.2  .RES
  677.     ---------
  678.  
  679.             .RES is created when votemgr is run with the /r: option, and
  680.         is the list of results. This file is overwritten if votemgr is
  681.         run again with more information in the related .VOT file.
  682.  
  683.             .RES is the same file that is posted in the (optional) echo
  684.         area to announce results, if and only if electoral period has
  685.         expired.
  686.  
  687.  
  688.     7.3  .QUO
  689.     ---------
  690.  
  691.             .QUO is created when votemgr is run with the /r: option, and
  692.         is the list of systems participating in the election. This is
  693.         the "quorum" file. This file is overwritten if votemgr is run
  694.         again with more information in the related .VOT file.
  695.  
  696.             .QUO is the same file that is posted in the (optional) echo
  697.         area to announce participating systems, if and only if electoral
  698.         period has expired.
  699.  
  700.  
  701.     7.4  .FLG
  702.     ---------
  703.  
  704.             .FLG is created when votemgr is run with the /r: option, and
  705.         packets are created. This file is void, but acts as a semaphore
  706.         to sign that results have already been posted in the echoarea.
  707.  
  708.  
  709.  
  710.  
  711.  ----------------
  712.  8   ERRORLEVELS
  713.  ----------------
  714.  
  715.         0: VOTEMGR Successful
  716.         5: VOTEMGR Error: Too few arguments
  717.         x: VOTEMGR Error: other errors
  718.  
  719.  
  720.  
  721.  -------------------
  722.  9   CLOSING MATTER
  723.  -------------------
  724.  
  725.          If you have any problems you can't fix or questions you can't
  726.      answer then please contact me via NetMail.  I will always do my
  727.      best to support the software, but the unregistered version is, by
  728.      definition, un-supported. I will answer queries as time allows,
  729.      please be patient when awaiting a reply.
  730.  
  731.      -------------------------------------------------------------------
  732.